System Requirements

The executables were compiled and tested using Windows 8.  If you do not have access to Windows 8, see the second to last
Section of the Instructions.


Software Dependencies

1. Loni Pipeline.  The latest version can be downloaded from http://pipeline.loni.usc.edu/ .  
The download for version 6.0.1 Windows is also included in the download folder.  This is the version used to test the
most recent Registration and Meshing Pipelines.

2.  TetView is needed for viewing the tetrahedral meshes.  Can be downloaded from http://wias-berlin.de/software/tetgen/tetview.html .
The executable for TetView is also included in the folder.

3.  BrainSuite is needed to read the (.img,.hdr) files that the Program uses as input and output. It can be downloaded
from http://www.loni.usc.edu/Software/BrainSuite .


Getting Started

The RegTM folder needs to be placed at C:\  .  Then go to the folder C:\RegTM\Pipelines and open up either MeshTM_v2.00 or RegTM_v1.00 
and clicke the green play arrow. 


Pipeline Help

The Loni Pipeline should make it relatively easy to modify the Registration/Meshing Software and add other programs to the pipeline.  
Detailed instructions for using Pipeline can be found at: http://pipeline.bmap.ucla.edu/learn/quick-start/  .


More General Information on the Meshing and Registration Methods

The Meshing Paper ( "The generation of tetrahedral mesh models for neuroanatomical MRI" , C. Lederman ) can be found at:
http://www.sciencedirect.com/science/article/pii/S1053811910014436

The Registration Paper ( "A Unified Variational Volume Registration Method Based on Automatically 
Learned Brain Structures" C. Lederman ) can be found at:
http://link.springer.com/article/10.1007/s10851-015-0604-x


Major Meshing Changes since version 1

1.  A bug was present in the Linear Solver, which somewhat adversely affected results

2.  The initial mesh is still voxelized. But the Active Contour computation uses a linear interpolation of the image
that chops corners of voxels or fills in corners of voxels.  


Parameters

Meshing Parameters

The parameters below can all be changed in the Parameters module

timestep_size -> Can be reduced if the program is crashing
timestep_number -> can be increased to improve results
Smoothing_Parameter -> Smooths out the mesh
AC_parameter -> higher values increase fidelity to the image
Boundary_Drift_Allowance_Parameter -> Can be increased from 0 to allow the nodes to drift way from the image 
boundary without penalty
Kappa ->  Sobolev Gradient Parameter.  Higher smooths out the result of each update
k1 ->  higher values increase stretch resistance
k2 -> higher values increase shear resistance
k3 -> higher values increase volume change resistance
e1 -> values over 0 allow some free stretch without penalty
e2 -> values over 0 allow some free shear without penalty
e3 -> values over 0 allow some free volume change without penalty
ls_derivative_smoothing -> To avoid computing the true inverse of nearly flat elements for the active contour
calculations, a matrix inverse approximation is computed.  Setting this to 0 gives the true inverse and higher
values give a smoothed out result for the nearly these nearly inverted morphed elements. 

Registration Parameters

These Parameters can be changed on each of the three Morphing modules

zoom_level ->  do not change
timestep -> If the mesh does not morph all the way to the target image, one reason may simply be that more 
timesteps are needed
dt  -> if the output text says that the inverted count is very high and crashes, try reducing the size of dt
alpha -> controls resistance to volume compression
beta -> controls resistance to stretch and shear
ac_eps -> (same role as ls_derivative_smoothing in the meshing) 


Viewing Output

Meshes->  Open TetView and Select ' Mesh files (*.{ele,face,edge}) '.  Open 'Pipeline_output' and other mesh folders and a .ele or .face file.

Images->  Open a .img file with Brainsuite.


Raw Code

The raw code is in very very poor shape, is not annotated and is not really intended to be shared.  However, if you cannot get the
executables to run on your system, or need to modify something that cannot be changed in the pipeline program, the code is there. 
It is in the folder 'other_sys'  Simply build the code in each folder and place the new executable in the corresponding folder
that is accessed by the pipeline.


Help

Please send me an email at carl.lederman@gmail.com if you believe something is not working as intended.  I have a full time job unrelated 
to this, but I will do what I can, if needed.